MaskTools2

From Avisynth wiki
Jump to: navigation, search
Abstract
Author tp7, Kurosu, Manao, mg262
Version 2.0b1
Download
Category Support filters
License MIT but binaries are GPLv2
Discussion Doom9 Thread

Contents

MaskTools2 b1

This is a fork of Manao's MaskTools2 plugin. It mostly contains performance improvements, bugfixes and some little things that make the plugin more "mature". This branch will be called b* as opposed to a* like the original MaskTools2.

Difference to MaskTools2 a48

  • Works correctly with AviSynth 2.6 Alpha 4/5 (including MT). Doesn't work with previous alphas.
  • Much cleaner and easy to understand codebase, also the source code is now licensed under MIT.
  • No MMX-optimized versions. MMX is too old to support and is always slower than SSE2.
  • all luts: faster LUT calculation, faster startup, reduced memory footprint if the same LUT is used for multiple planes or some planes aren't processed. For example mt_lutxyz(c1, c2, c3, "x y + z -") will use only 16MBs of memory instead of 48MBs.
  • mt_lutspa: does not depend on source clip performance as it doesn't get requested at all (unless mode 2 is used). Always much faster (5-o9k times).
  • all filters: faster modes 2, 4 and 5 (copy), negative (memset) modes.
  • mt_hysteresis: 3-4 times better performance.
  • all luts: performance in mode 3 with an empty LUT is now identical to mode 2. Thus mt_lut(chroma="128") is a bit faster than Grayscale() instead of being much slower.
  • mt_merge: luma=true now supports YV24.
  • mt_luts: correct value is used as x. More info here.
  • sobel/roberts/laplace modes of mt_edge: better performance when SSSE3 is available.
  • mt_edge("cartoon"): 10 times faster when SSE2 is available.
  • all asm-optimized filters: same performance on any resolution up to mod-1. Original MaskTools2 used unoptimized version for any non-mod8 clips.

All filters were tested on a Core i7 860. Performance might be a bit different on other CPUs.

Download

MaskTools b1 comes in three variations:


Runtime dependencies:

**** vcredist_x86.exe is required for MaskTools2-x86
**** vcredist_x64.exe is required for MaskTools2-x64


Introduction

MaskTools2 contain a set of filters designed to create, manipulate and use masks. Masks, in video processing, are a way to give a relative importance to each pixel. You can, for example, create a mask that selects only the green parts of the video, and then replace those parts with another video. To give the most control over the handling of masks, the filters will use the fact that each luma and chroma planes can be uncorrelated. That means that a single video will always be considered by the filters as 3 independent planes. That applies for masks as well, which means that a mask clip will in fact contain 3 masks, one for each plane.

The filters have a set of common parameters, that mainly concern what processing to do on each plane. All filters only work with planar colorspaces (Y8, YV12, YV16, and YV24 (AviSynth 2.5.8 only supports YV12!).

Common parameters

As said previously, all the filters - except the helpers - share a common set of parameters. These parameters are used to tell what processing to do on each plane / channel, and what area of the video to process.

offX int = 0
offY int = 0
offx and offy are the top left coordinates of the box where the actual processing shall occur. Everything outside that box will be garbage.


w int = -1
h int = -1
w and h are the width and height of the processed box. -1 means that the box extends to the lower right corner of the video.
This also means that default settings are meant to process the whole picture.


Y int = 3
U int = 1
V int = 1
These three values describe the actual processing mode that is to be used on each plane / channel. Here is how the modes are coded :
  • x = -255..0 : all the pixels of the plane will be set to -x.
  • x = 1 : the plane will not be processed. That means the content of the plane after the filter is pure garbage.
  • x = 2 : the plane of the first input clip will be copied.
  • x = 3 : the plane will be processed with the processing the filter is designed to do.
  • x = 4 (when applicable) : the plane of the second input clip will be copied.
  • x = 5 (when applicable) : the plane of the third input clip will be copied.
As you can see, defaults parameters are chosen to only process the luma, and not to care about the chroma. It's because most video processing doesn't touch the chroma when handling 4:2:0.


chroma string = ""
When defined, the value contained in this string will overwrite the U & V processing modes.
This is a nice addition proposed by mg262 that makes the filter more user friendly. Allowed values for chroma are:
  • "process" : set u = v = 3.
  • "copy" or "copy first" : set u = v = 2.
  • "copy second" : set u = v = 4.
  • "copy third" : set u = v = 5.
  • "xxx", where xxx is a number : set u = v = -xxx.


Filters

Here is an exhaustive list of the filters contained in MaskTools2 (see developer's page here for more information)

Filter Description Color format
Masks creation
Mt_edge

Creates edge masks.

YV12
Mt_motion

Creates motion masks.

YV12
Masks operation
Mt_invert

Inverses masks.

YV12
mt_binarize

Transforms soft masks into hard masks.

YV12
mt_logic

Combines masks using logic operators.

YV12
mt_hysteresis

Combines masks making the first one to grow into the second.

YV12
Masks merging
Mt_merge

Merges two clips according to a mask.

YV12
Morphologic operators
mt_expand

Expands the mask / the video.

YV12
mt_inpand

Inpands the mask / the video.

YV12
mt_inflate

Inflates the mask / the video.

YV12
mt_deflate

Deflates the mask / the video.

YV12
LUT operators
mt_lut

Applies an expression to all the pixels of a mask / video.

YV12
mt_lutxy

Applies an expression to all the pixels of two masks / videos.

YV12
mt_lutxyz

Applies an expression to all the pixels of three masks / videos.

YV12
mt_lutf

Creates a uniform picture from the collection of computation on pixels of two clips.

YV12
mt_luts

Applies an expression taking neighbouring pixels into.

YV12
mt_lutsx

Applies an expression taking neighbouring pixels into, in a different way.

YV12
mt_lutspa

Computes the value of a pixel according to its spatial position.

YV12
Support operators
mt_makediff

Substracts two clips.

YV12
mt_adddiff

Adds back a difference of two clips.

YV12
mt_clamp

Clamps a clip between two other clips.

YV12
mt_average

Averages two clips.

YV12
Convolutions
mt_convolution

Applies a separable convolution on the picture.

YV12
mt_mappedblur

Applies a special 3x3 convolution on the picture.

YV12
Helpers
mt_square

Creates a string describing a square.

YV12
mt_rectangle

Creates a string describing a rectangle.

YV12
mt_freerectangle

Creates a string describing a rectangle.

YV12
mt_diamond

Creates a string describing a diamond.

YV12
mt_losange

Creates a string describing a lozenge.

YV12
mt_freelosange

Creates a string describing a lozenge.

YV12
mt_circle

Creates a string describing a circle.

YV12
mt_ellipse

Creates a string describing an ellipse.

YV12
mt_freeellipse

Creates a string describing an ellipse.

YV12
mt_polish

Creates a reverse polish expression from an infix one.

YV12
mt_infix

Creates an infix expression from a reverse polish one.

YV12


Reverse polish notation

A lot of filters accept custom functions defined by an expression written in reverse polish notation. You may not be accustomed to this notation, so here are a few pointers :

  • The basic concept behind the notation is to write the operator / function after the arguments. Hence, "x + y" in infix notation becomes in reverse polish "x y +". "(3 + 5) * x" would become "3 5 + x *".
  • As you noticed in the last example, the great asset of the notation is that it doesn't need parenthesis. The expression that would have been enclosed in parenthesis ( "3 + 5" ) is correctly computed, because we read the expression from left to right, and because when the "+" is encountered, its two operands are unmistakeably known.
  • The supported operators are : "+", "-", "*", "/", "%" (modulo) and "^" (power)
  • The supported functions are : "sin", "cos", "tan", "asin", "acos", "atan", "exp", "log", "abs", "round", "clip", "min", "max".
  • Making the assumption that a positive float is "true", and a negative one is "false", we can also define boolean operators : "&", "|", "&!" (and not), "?°" (xor).
  • We can create boolean values with the following comparison operators : "<", ">", "<=", ">=", "!=", "==", "=".
  • The variable "x" and "y" (when applicable) contains the value of the pixel. It's an integer that ranges from 0 to 255.
  • The constant "pi" can be used.
  • Finally, there's a ternary operator : "?", which acts like a "if .. then .. else .."
  • All the computations are made in floats, and the final result is rounded to the nearest integer, in the range [0..255].
  • Throughout the whole documentation, you'll be able to find plenty of examples.


Changelog

See the GitHub commit log for all changes.


Exernal Links

  • GitHub - Source code repository.
  • Doom9 Forum - Original MaskTools2 discussion thread.

Guides:



Back to External Filters ←

Retrieved from "http://avisynth.nl/index.php?title=MaskTools2&oldid=4860"
Personal tools